Code
if not .Site.Params.disable_codefolding }}
{{ <script src="{{ "js/collapse.js" | relURL }}"></script>
<script src="{{ "js/dropdown.js" | relURL }}"></script>
<script src="{{ "js/transition.js" | relURL }}"></script>
{{ end }}
James E. Pustejovsky
April 14, 2019
June 8, 2024
2024-06-08 I have ported my website to Quarto, which has native support for code folding. I’m leaving this post up despite the fact that the functionality is no longer relevant for this website.
2020-05-03 This post describes an implementation of code folding for an older version of the Academic Theme. It does not work with Academic 4.+. See my updated instructions to get it working with newer versions of Academic.
Rmarkdown documents now have a very nifty code folding option, which allows the reader of a compiled html document to toggle whether to view or hide code chunks. However, the feature is not supported in blogdown, the popular Rmarkdown-based website/blog creation package. I recently ran across an implementation of codefolding for blogdown, developed by Sébastien Rochette. I have been putzing around, trying to get it to work with my blog, which uses the Hugo Academic theme—alas, to no avail. To my amazement and good fortune, Sébastien swooped in with a pull request that cleaned up my blundering attempts at implementation. Now all of my posts have working code folding!
In this post, I’ll lay out how to make Sébastien’s code folding feature work with the Academic theme. To be totally clear, all of the hard bits of this were solved by Sébastien. I don’t know javascript to save my life, and my only contribution is to write down the instructions in what I hope is a coherent fashion, so that you too can soon be doing the happy code folding dance if you so desire.
You’ll first need to pull in some javascript assets. Create a folder called js
under the \static
directory of your site. Add the files transition.js
, collapse.js
, and dropdown.js
from bootstrap.
Also add Sébastien’s codefolding javascript, codefolding.js
.
Create a folder called css
under the \static
directory of your site. Add the file codefolding.css
. This is the css for the buttons that will appear on your posts.
Add the file article_footer_js.html
to the \layouts\partials
directory of your site.
Add the file header_maincodefolding.html
to the \layouts\partials
directory of your site.
If you do not already have a file head_custom.html
in the \layouts\partials
directory, create it. Add the following lines of code to the file:
If you do not already have a file footer.html
in the \layouts\partials
directory, copy it over from \themes\hugo-academic\layouts\partials
. Add the following lines of code to it, somewhere towards the bottom:
If you do not already have the file single.html
in the directory \layouts\_default
, copy it over from \themes\hugo-academic\layouts\_default
. Add the following line of code at an appropriate point so that your posts will include the “Show/hide code” button (I put it after the title, before the meta-data):
Modify your config.toml
file (in the base directory of your site) to include the following lines:
Also edit the custom_css
parameter so that the codefolding.css
file will get loaded:
The config.toml
file now has three parameters that control code folding:
disable_codefolding
controls whether to load the code folding scripts on your site. Set it to true
to disable code folding globally.codefolding_show
controls whether code blocks will be shown or hidden by default. If your previous posts have lots of code in them, set the default to show
to minimize changes in the appearance of your site.codefolding_nobutton
controls whether the “Show/hide code” button will appear at the top of posts that include code blocks. Set it to true
to disable the button but keep the other code folding functionality.The above parameters are defaults for your entire site. To over-ride the defaults, you can also set the parameters in the YAML header of any post:
disable_codefolding: true
to turn off code folding for the post.codefolding_show: hide
to hide the code blocks in the post (as in this post).codefolding_nobutton: true
to turn off the “Show/hide code” button at the top of the post (as in the present post).I hope these instructions work for you. If not, questions, corrections, and clarifications are welcome. Thanks again to Sébastien Rochette for working out this solution and for graciously troubleshooting my attempt at implementation. Happy blogging, y’all!